---
title: Images
description: Apprendre à utiliser les images dans Astro.
i18nReady: true
---
import Since from '~/components/Since.astro';


Astro fournit plusieurs façons d'utiliser les images sur votre site, qu'elles soient stockées localement dans votre projet, liées à distance ou stockées dans un CMS ou un CDN !

### Dans les fichiers `.astro`

Astro utilise les éléments HTML `<img>` pour afficher les images, et tous les attributs HTML des images sont supportés.

L'attribut `src` est requis, et son format va dépendre de l'endroit où les images sont situées :

```astro title="src/pages/index.astro"
---
import rocket from '../images/rocket.svg';
---
<!-- Image distante sur un autre serveur -->
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro">
<!-- Image locale située à public/assets/stars.png -->
<img src="/assets/stars.png" alt="Un ciel nocturne étoilé.">
<!-- Image locale située à src/images/rocket.svg -->
<img src={rocket} alt="Une fusée dans l'espace."/>
```

### Dans les fichiers Markdown

Vous pouvez utiliser la syntaxe Markdown standard  `![]()` ou les balises HTML standard `<img>` dans vos fichiers `.md` pour les images situées dans votre dossier `public/`, ou pour les images distantes sur un autre serveur.

Si vous ne pouvez pas garder vos images dans `public/`, nous vous recommandons d'utiliser le format de fichier `.mdx`, qui vous permet de combiner des composants importés avec une syntaxe semblable à celle de Markdown. Utilisez [l'intégration MDX](/fr/guides/integrations-guide/mdx/) pour ajouter le support de MDX à Astro.

```md
<!-- src/pages/post-1.md -->

# Ma Page Markdown

<!-- Image locale située à public/assets/stars.png -->
![Un ciel nocturne étoilé.](/assets/stars.png)
<img src="/assets/stars.png" alt="Un ciel nocturne étoilé.">

<!-- Image distante sur un autre serveur -->
![Astro](https://astro.build/assets/logo.png)
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro">
```

### Dans les fichiers MDX

Vous pouvez utiliser la syntaxe Markdown standard `![]()` ou les balises JSX `<img />` dans vos fichiers `.mdx` pour afficher des images depuis votre dossier `public/` ou depuis un serveur distant.

De plus, vous pouvez importer et utiliser des images situées dans votre répertoire de projet `src/`, comme vous le feriez dans des composants Astro.

```mdx title="src/pages/post-1.mdx"
import rocket from '../images/rocket.svg';

# Ma Page MDX

// Image locale située à src/images/rocket.svg
<img src={rocket} alt="Une fusée dans l'espace."/>

// Image locale située à public/assets/stars.png
![Un ciel nocturne étoilé.](/assets/stars.png)
<img src="/assets/stars.png" alt="Un ciel nocturne étoilé." />

// Image distante sur un autre serveur
![Astro](https://astro.build/assets/logo.png)
<img src="https://astro.build/assets/logo.png" width="25" alt="Astro" />
```

### Dans les Composants de Framework UI

Lorsque vous ajoutez des images dans un [composant de Framework UI](/fr/core-concepts/framework-components/) (ex : React, Svelte), utilisez la syntaxe des images appropriée pour ce Framework de composants particulier.

## Où stocker les images

### `src/`
Vos images stockées dans `src/` peuvent être utilisées par les composants (`.astro`, `.mdx` et autres Frameworks UI) mais pas dans les fichiers Markdown.

Nous recommandons de garder vos images dans [`public/`](#public) ou de les stocker [à distance](#utilisation-des-images-depuis-un-cms-ou-un-cdn) si vous devez utiliser des fichiers Markdown.

Importez-les depuis un **chemin de fichier relatif** ou un [alias d'import](/fr/guides/aliases/) dans n'importe quel fichier composant et utilisez ensuite l'import comme attribut `src` de l'image.

```astro
---
// src/pages/index.astro

// Accéder aux images dans `src/images/`
import logo from '../images/logo.png';
---
<img src={logo} width="40" alt="Astro" />
```

### `public/`

Vos images stockées dans `public/` peuvent être utilisées par les composants (`.astro`, `.mdx` et autres Frameworks UI) mais aussi dans les fichiers Markdown.


Cependant les fichiers dans le répertoire `/public` sont toujours utilisés ou copiés tels quels, sans aucun traitement. Si vous utilisez des images en dehors des fichiers Markdown, nous vous recommandons de les conserver  dans le dossier `src` lorsque cela est possible afin qu'Astro puisse les transformer, les optimiser et les regrouper.

L'attribut `src` est **relatif au dossier public**. Dans Markdown, vous pouvez aussi utiliser la notation `![]()`.

```astro title="src/pages/index.astro"
---
// Accéder aux images dans `public/images/`
---
<img src="/images/logo.png" />
```

## Intégration des images Astro

L'intégration officielle d'Astro des images fournit deux composants Astro différents pour rendre des images optimisées, `<Image />` et `<Picture />`. Celle-ci est supportée pour tous les sites statiques et pour [certains hébergeurs de déploiement rendu côté serveur](/fr/guides/integrations-guide/image/#installation).

Après [avoir installé `@astrojs/image`](/fr/guides/integrations-guide/image/#installation), vous pouvez utiliser ces deux composants partout où vous pouvez utiliser des composants Astro : dans les fichiers `.astro` et `.mdx`.

### `<Image />`

Le [composant Astro `<Image />`](/fr/guides/integrations-guide/image/#image-) vous permet d'optimiser une seule image et de spécifier sa largeur, hauteur, et/ou son rapport rapport largeur/hauteur. Vous pouvez même convertir votre image dans un format de sortie particulier.

Ce composant est utile pour les images qui doivent conserver une taille constante sur tous les écrans ou pour contrôler étroitement la qualité d'une image (ex : les logos).

Pour les images responsive, ou pour une direction artistique, utilisez plutôt le composant `<Picture />`.

#### Images distantes

(attributs requis : [`src`](/fr/guides/integrations-guide/image/#src), [`alt`](/fr/guides/integrations-guide/image/#alt), [`format`](/fr/guides/integrations-guide/image/#format), et dimensions)

Passez une URL complète à l'attribut `src` du composant `<Image />` et incluez une valeur pour `alt`.

Le composant `<Image />` ne peut pas déterminer le format de fichier d'origine d'une image distante, vous devez donc fournir un `format` de sortie (ex : png, avif) pour convertir votre image distante.

Vous devez également fournir soit [`width`](/fr/guides/integrations-guide/image/#width) et [`height`](/fr/guides/integrations-guide/image/#height), soit l'une des dimensions et un [`aspectRatio`](/fr/guides/integrations-guide/image/#aspectratio) pour éviter les décalages de mise en page du contenu car le composant `<Image />` ne connaît pas les dimensions d'une image distante.

[Toutes les autres propriétés](/fr/guides/integrations-guide/image/#image-) sont facultatives.

#### Images locales dans `src/`

(attributs requis : [`src`](/fr/guides/integrations-guide/image/#src), et [`alt`](/fr/guides/integrations-guide/image/#alt))

Importez votre image dans le Frontmatter et passez-la directement à l'attribut `src` du composant `<Image />`.

`alt` est requis, mais [toutes les autres propriétés](/fr/guides/integrations-guide/image/#image-) sont facultatives et, si elles ne sont pas fournies, prendront par défaut les propriétés d'origine du fichier image.

#### Images dans `public/`

(attributs requis : [`src`](/fr/guides/integrations-guide/image/#src), [`alt`](/fr/guides/integrations-guide/image/#alt), [`format`](/fr/guides/integrations-guide/image/#format), et dimensions)

Passez un chemin relatif au répertoire public à l'attribut `src` du composant `<Image />` et incluez une valeur pour `alt`.

Elle sera traitée comme une image distante, ce qui nécessite à la fois [`width`](/fr/guides/integrations-guide/image/#width) et [`height`](/fr/guides/integrations-guide/image/#height), ou une dimension et un attribut [`aspectRatio`](/fr/guides/integrations-guide/image/#aspectratio).

Une valeur pour l'attribut `format` (ex : png, avif) est requise afin de transformer votre image.

[Toutes les autres propriétés](/fr/guides/integrations-guide/image/#image-) sont facultatives.

Votre image d'origine sera copiée sans traitement dans le dossier de Build, comme tous les fichiers situés dans `public/`, et l'intégration d'image d'Astro renverra également des versions optimisées de l'image.

#### Exemples

```astro
---
// src/pages/index.astro
import { Image } from '@astrojs/image/components';
import localImage from "../assets/logo.png";
const remoteImage = "https://picsum.photos/id/957/300/200.jpg";
const localAlt = "Le logo d'Astro";
const remoteAlt = "Une vue en contre-plongée d'une forêt pendant la journée";
---

<!-- Image locale optimisée, gardant la largeur, la hauteur et le format d'image d'origine -->
<Image src={localImage} alt={localAlt} />

<!-- La hauteur sera recalculée pour correspondre au ratio d'aspect original -->
<Image src={localImage} width={300} alt={localAlt} />

<!-- Pour les images distantes, les dimensions désirées et le format sont requis -->
<Image src={remoteImage} width={300} aspectRatio="1:1" format="png" alt={remoteAlt} />

<!-- recadrage à une largeur et une hauteur spécifiques -->
<Image src={localImage} width={300} height={600} alt={localAlt}/>
<Image src={remoteImage} width={544} height={184} format="png" alt={remoteAlt}/>

<!-- recadrage à un ratio d'aspect spécifique et conversion vers un format AVIF -->
<Image src={localImage} aspectRatio="16:9" format="avif" alt={localAlt}/>
<Image src={remoteImage} height={200} aspectRatio="16:9" format="avif" alt={remoteAlt}/>

<!-- les importations d'images locales peuvent également être directement intégrées -->
<Image src={import('../assets/logo.png')} alt={localAlt}/>

<!-- Si une image est située dans le dossier `/public`, utilisez son chemin relatif à `/public` -->
<Image src="/penguin.jpg" width="300" aspectRatio={1} format="png" alt="A happy penguin"/>
```

### `<Picture /> `

Le [composant Astro `<Picture />`](/fr/guides/integrations-guide/image/#picture-) peut être utilisé pour fournir des images responsive sur votre site, y compris plusieurs tailles, formats et mises en page d'image.

Vous pouvez laisser le navigateur de l'utilisateur choisir les tailles d'image, les résolutions et les types de fichiers appropriés en fonction de facteurs tels que la taille d'écran et la bande passante. Ou alors, vous pouvez spécifier des règles que le navigateur doit suivre en fonction des media queries.

Ce composant est utile pour optimiser ce que votre utilisateur voit à différentes tailles d'écran, ou pour la direction artistique.

:::tip
Consultez le guide de MDN pour plus d'informations sur [les images responsive et la direction arstistique](https://developer.mozilla.org/fr/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#d%C3%A9cision_de_nature_artistique).
:::

#### Images distantes

(attributs requis : [`src`](/fr/guides/integrations-guide/image/#src-1), [`widths`](/fr/guides/integrations-guide/image/#widths), [`sizes`](/fr/guides/integrations-guide/image/#sizes), [`alt`](/fr/guides/integrations-guide/image/#alt-1), et [`aspectRatio`](/fr/guides/integrations-guide/image/#aspectratio-1))

Passez une URL complète à l'attribut `src` du composant `<Picture />`.

Une valeur pour `aspectRatio` est également requise pour s'assurer que la hauteur correcte des images distantes puisse être calculée au moment du Build.

Vous devez fournir au composant des indications sur les largeurs d'image et les tailles d'écran, mais [toutes les autres propriétés](/fr/guides/integrations-guide/image/#picture-) sont facultatives.

Bien que [`formats`](/fr/guides/integrations-guide/image/#formats) ne soit pas requis, le format d'image d'origine des images distantes est inconnu et ne sera pas inclus par défaut. S'il n'est pas fourni, seuls `webp` et `avif` seront inclus.

#### Images locales

(attributs requis : [`src`](/fr/guides/integrations-guide/image/#src-1), [`widths`](/fr/guides/integrations-guide/image/#widths), [`sizes`](/fr/guides/integrations-guide/image/#sizes), [`alt`](/fr/guides/integrations-guide/image/#alt-1))

Importez votre image dans Frontmatter et passez-la directement à l'attribut `src` du composant `<Picture />`.

Vous devez fournir au composant des indications sur les largeurs d'image et les tailles d'écran, mais [toutes les autres propriétés](/fr/guides/integrations-guide/image/#picture-) sont facultatives.

Par défaut, les [`formats`](/fr/guides/integrations-guide/image/#formats) du composant `<Picture />` incluront `avif` et `webp` en plus du format d'origine de l'image s'il n'est pas spécifié.

#### Images dans `public/`

(attributs requis : [`src`](/fr/guides/integrations-guide/image/#src-1), [`widths`](/fr/guides/integrations-guide/image/#widths), [`sizes`](/fr/guides/integrations-guide/image/#sizes), [`alt`](/fr/guides/integrations-guide/image/#alt-1), et [`aspectRatio`](/fr/guides/integrations-guide/image/#aspectratio-1))

Passez à l'attribut `src` du composant un chemin relatif au dossier public et incluez une valeur pour `alt`.

L'image sera traitée comme une image distante, donc une valeur pour `aspectRatio` est également requise pour s'assurer que la hauteur puisse être correctement calculée au moment du Build.

Vous devez fournir au composant des indications sur les largeurs d'image et les tailles d'écran, mais [toutes les autres propriétés](/fr/guides/integrations-guide/image/#picture-) sont facultatives.

Bien que [`formats`](/fr/guides/integrations-guide/image/#formats) ne soit pas requis, le format d'origine des images dans le dossier `public/` est inconnu et ne sera pas inclus par défaut. S'il n'est pas fourni, seuls "webp" et "avif" seront inclus.

Votre image d'origine sera copiée sans traitement dans le dossier de Build, comme tous les fichiers situés dans `public/`, et l'intégration d'image d'Astro renverra également des versions optimisées de l'image.

#### Exemples

```astro
---
import { Picture } from '@astrojs/image/components';
import localImage from '../assets/logo.png';
const remoteImage = 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png';
---

<!-- Image locale avec plusieurs tailles et formats -->
<Picture src={localImage} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" formats={['avif', 'jpeg', 'png', 'webp']} alt="The Astro logo" />

<!-- Image distante (le rapport d'aspect est requis) -->
<Picture src={remoteImage} widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="Le logo Google" />

<!-- Les images dans /public fonctionnent comme les images distantes -->
<Picture src="/logo.png" widths={[200, 400, 800]} aspectRatio="4:3" sizes="(max-width: 800px) 100vw, 800px" alt="Le logo Google" />

<!-- Les imports directs sont supportés -->
<Picture src={import("../assets/logo.png")} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="Le logo Google" />

```


### Using in MDX

Dans les fichiers `.mdx`, `<Image />` et `<Picture />` peuvent recevoir votre `src` de l'image via des imports et exports.
```mdx
// src/pages/index.mdx

import { Image, Picture } from '@astrojs/image/components';
import rocket from '../assets/rocket.png';
export const galaxy = 'https://astro.build/assets/galaxy.jpg';

<Image src={import('../assets/logo.png')} alt="Astro"/>
<Image src={rocket} width={300} alt="Fusée approchant la lune."/>
<Picture src={rocket} widths={[200, 400, 800]} sizes="(max-width: 800px) 100vw, 800px" alt="Une fusée qui décolle." />
<Picture src={galaxy} widths={[200, 400, 800]} aspectRatio={16/9} sizes="(max-width: 800px) 100vw, 800px" alt="Le cosmos." />
```

### Réglage des valeurs par défaut

Actuellement, il n'existe aucun moyen de spécifier des valeurs par défaut pour tous les composants `<Image />` et `<Picture />`. Les attributs requis doivent être définis sur chaque composant.

Comme alternative, vous pouvez encapsuler ces composants dans un autre composant Astro pour les réutiliser. Par exemple, vous pouvez créer un composant pour les images de votre article de blog :

```astro title="src/components/BlogPostImage.astro"
---
import { Picture } from '@astrojs/image/components';

const {src, ...attrs} = Astro.props;
---
<Picture src={src} widths={[400, 800, 1500]} sizes="(max-width: 767px) 100vw, 736px" {...attrs} />

<style>
  img, picture :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

### Utilisation de `<img>` avec l'intégration d'image

L'intégration d'image officielle modifiera les importations d'images pour renvoyer un objet plutôt qu'une chaîne de caractères source.
L'objet possède les propriétés suivantes, dérivées du fichier importé :
```ts
{
  src: string;
  width: number;
  height: number;
  format: 'avif' | 'gif' | 'heic' | 'heif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp';
}
```

Si l'intégration d'image est installée, reportez-vous à la propriété `src` de l'objet lors de l'utilisation de `<img>`.

```astro ".src"
---
import rocket from '../images/rocket.svg';
---
<img src={rocket.src} alt="Une fusée dans l'espace."/>
```

Une alternative consiste à ajouter `?url` à vos imports pour leur dire de renvoyer une chaîne de caractères source.

```astro "?url"
---
import rocket from '../images/rocket.svg?url';
---
<img src={rocket} alt="Une fusée dans l'espace."/>
```

## Utilisation des Images depuis un CMS ou un CDN

Les CDN d'images fonctionnent avec Astro. Utilisez l'URL complète d'une image comme attribut `src` dans une balise `<img>` ou une notation Markdown.

Alternativement, si le CDN fournit un SDK Node.js, vous pouvez l'utiliser dans votre projet. Par exemple, [le SDK de Cloudinary](https://cloudinary.com/documentation/node_integration) peut générer la balise `<img>` avec le `src` approprié pour vous.

Pour utiliser des [images externes avec les composants `<Image />`](#images-distantes) et [`<Picture />`](#images-distantes-1) de l'intégration d'image d'Astro, vous devez spécifier les valeurs de dimension et de format pour travailler avec des images distantes.

## Texte Alternatif

Tous les utilisateurs ne peuvent pas voir les images de la même manière, l'accessibilité est donc une préoccupation particulièrement importante lors de l'utilisation d'images. Utilisez l'attribut `alt` pour fournir un [texte alternatif descriptif](https://www.w3.org/WAI/tutorials/images/) pour les images.

Cet attribut est requis pour les composants `<Image />` et `<Picture />` de l'intégration d'image. Ces composants génèrent une erreur si aucun texte alternatif n'est fourni.

Si l'image est simplement décorative (i.e. elle ne contribue pas à la compréhension de la page), définissez `alt=""` pour que les lecteurs d'écran sachent ignorer l'image.


## Intégrations Communautaires

En plus de l'intégration [`@astrojs/image`](/fr/guides/integrations-guide/image/) officielle, il existe plusieurs [intégrations d'images communautaires](https://astro.build/integrations?search=images) pour optimiser et travailler avec des images dans votre projet Astro.
